home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / LinkVar.3 < prev    next >
Text File  |  1994-09-20  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tcl_LinkVar(3)       Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_LinkVar, Tcl_UnlinkVar - link Tcl variable to C variable
  12.  
  13. SYNOPSIS
  14.      #include <tcl.h>
  15.  
  16.      int
  17.      Tcl_LinkVar(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _a_d_d_r, _t_y_p_e)
  18.  
  19.      Tcl_UnlinkVar(_i_n_t_e_r_p, _v_a_r_N_a_m_e)
  20.  
  21. ARGUMENTS
  22.      Tcl_Interp   *_i_n_t_e_r_p    (in)      Interpreter that  contains
  23.                                        _v_a_r_N_a_m_e.    Also  used  by
  24.                                        Tcl_LinkVar   to    return
  25.                                        error messages.
  26.  
  27.      char         *_v_a_r_N_a_m_e   (in)      Name of global variable.
  28.  
  29.      char         *_a_d_d_r      (in)      Address of C variable that
  30.                                        is  to  be  linked to _v_a_r_-
  31.                                        _N_a_m_e.
  32.  
  33.      int          _t_y_p_e       (in)      Type of C variable.  Must
  34.                                        be one of TCL_LINK_INT,
  35.                                        TCL_LINK_DOUBLE,
  36.                                        TCL_LINK_BOOLEAN, or
  37.                                        TCL_LINK_STRING, option-
  38.                                        ally OR'ed with
  39.                                        TCL_LINK_READ_ONLY to make
  40.                                        Tcl variable read-only.
  41. _________________________________________________________________
  42.  
  43.  
  44. DESCRIPTION
  45.      Tcl_LinkVar uses variable traces to keep  the  Tcl  variable
  46.      named  by _v_a_r_N_a_m_e in sync with the C variable at the address
  47.      given by _a_d_d_r.  Whenever the Tcl variable is read the  value
  48.      of  the  C  variable  will be returned, and whenever the Tcl
  49.      variable is written the C variable will be updated  to  have
  50.      the same value.  Tcl_LinkVar normally returns TCL_OK;  if an
  51.      error occurs while setting up the link (e.g. because _v_a_r_N_a_m_e
  52.      is  the  name  of  array)  then  TCL_ERROR  is  returned and
  53.      _i_n_t_e_r_p->_r_e_s_u_l_t contains an error message.
  54.  
  55.      The _t_y_p_e argument specifies the type of the C variable,  and
  56.      must have one of the following values, optionally OR'ed with
  57.      TCL_LINK_READ_ONLY:
  58.  
  59.      TCL_LINK_INT
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_LinkVar(3)       Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74.           The C variable is of type int.  Any value written  into
  75.           the  Tcl  variable  must  have  a  proper  integer form
  76.           acceptable  to  Tcl_GetInt;   attempts  to  write  non-
  77.           integer  values  into _v_a_r_N_a_m_e will be rejected with Tcl
  78.           errors.
  79.  
  80.      TCL_LINK_DOUBLE
  81.           The C variable is of type double.   Any  value  written
  82.           into  the  Tcl  variable  must  have a proper real form
  83.           acceptable to Tcl_GetDouble;  attempts  to  write  non-
  84.           real  values  into  _v_a_r_N_a_m_e  will  be rejected with Tcl
  85.           errors.
  86.  
  87.      TCL_LINK_BOOLEAN
  88.           The C variable is of type int.  If its  value  is  zero
  89.           then  it will read from Tcl as ``0''; otherwise it will
  90.           read from Tcl as ``1''.  Whenver _v_a_r_N_a_m_e  is  modified,
  91.           the  C  variable  will  be  set to a 0 or 1 value.  Any
  92.           value written into the Tcl variable must have a  proper
  93.           boolean form acceptable to Tcl_GetBoolean;  attempts to
  94.           write non-boolean values into _v_a_r_N_a_m_e will be  rejected
  95.           with Tcl errors.
  96.  
  97.      TCL_LINK_STRING
  98.           The C variable is of type char *.  If its value is  not
  99.           null  then  it  must be a pointer to a string allocated
  100.           with malloc.  Whenever the Tcl variable is modified the
  101.           current  C  string will be freed and new memory will be
  102.           allocated to hold a copy of the variable's  new  value.
  103.           If  the C variable contains a null pointer then the Tcl
  104.           variable will read as ``NULL''.
  105.  
  106.      If the TCL_LINK_READ_ONLY flag is present in _t_y_p_e  then  the
  107.      variable  will  be read-only from Tcl, so that its value can
  108.      only be changed by modifying the C  variable.   Attempts  to
  109.      write the variable from Tcl will be rejected with errors.
  110.  
  111.  
  112. KEYWORDS
  113.      boolean, integer, link, read-only, real, string, variable
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.